home *** CD-ROM | disk | FTP | other *** search
/ ShareWare OnLine 2 / ShareWare OnLine Volume 2 (CMS Software)(1993).iso / bbs_soft / flist26.zip / FLIST.DOC < prev    next >
Text File  |  1993-03-05  |  13KB  |  268 lines
  1.  
  2. FLIST -- Generates file lists based on privilege levels and keys
  3.  
  4. Version 2.6   (3/05/93)
  5.  
  6. Written by Bob Quinlan of Austin, Texas, USA
  7. Sysop of Red October at 512-834-2593 (1:382/111)
  8. Special thanks to David Powers for suggestions and code.
  9.  
  10. Copyright 1993 by Bob Quinlan
  11.  
  12. Compatible with Maximus 2.00 and 2.01
  13.  
  14.  
  15. This program generates a list of files that a user with a particular
  16. privilege level and set of keys could access.  It is intended to make
  17. the procedure independent of changes to the structure of your file
  18. areas.  Instead of specifying which areas should be included you just
  19. specify what sort of user you want the list to apply to.
  20.  
  21. You can also create lists of new files.  Just use /D to specify how many
  22. days of files you want to list.
  23.  
  24.     /Afile      Area file.  You can use this to specify a path to
  25.                 AREA.DAT or to refer to another file (although it must
  26.                 follow the AREA.DAT format).  The filename must be
  27.                 included along with the path.  Defaults to AREA.DAT in
  28.                 the current directory.
  29.  
  30.     /B          Include barricaded areas.  If this switch is not
  31.                 included no barricaded areas will be included.
  32.  
  33.     /C          Include comments from the FILES.BBS file lists.  By
  34.                 default only files and their descriptions are included.
  35.  
  36.                 Using this switch has one side-effect!  Normally area
  37.                 headers are only generated for areas that have files in
  38.                 them.  /C will cause them to be generated for any area
  39.                 that has comments as well.  Do not use /C if you only
  40.                 want areas that have files in them to appear!  (I
  41.                 recommend not using /C with /D so that you don't show
  42.                 lots of apparently empty file areas.)
  43.  
  44.     /Ddays      Days.  Excludes all files more than this many days old.
  45.                 Use this switch to create lists of new files.  You
  46.                 cannot use both this and the /M switch at the same time.
  47.  
  48.     /Ffile      Output file.  The pathname of the file you want the file
  49.                 list written to.  Defaults to FLIST.TXT in the current
  50.                 area.
  51.  
  52.     /HAfile     Area header file.  The contents of this file will be
  53.                 added to the report for each area header.  There are
  54.                 several sequences you can embed in the file that have
  55.                 special meanings.  All of the codes explained under /HS
  56.                 are allowed except for %C and %B.
  57.  
  58.                 If no area header file is specified a default header
  59.                 will be used.
  60.  
  61.     /HBfile     Beginning header file.  The contents of this file will
  62.                 be added to the beginning of the report.  There are
  63.                 several sequences you can embed in the file that have
  64.                 special meanings.  The codes %D, %T, and %A (explained
  65.                 under /HS) are allowed.
  66.  
  67.     /HEfile     End header file.  The contents of this file will be
  68.                 added to the end of the report.  There are several
  69.                 sequences you can embed in the file that have special
  70.                 meanings.  The codes %F, %S, %D, %T, and %A (explained
  71.                 under /HS) are allowed.
  72.  
  73.     /HSfile     Area summary header file.  The contents of this file
  74.                 will be added to the report after each area.  There are
  75.                 several sequences you can embed in the file that have
  76.                 special meanings:
  77.  
  78.                     %N will be replaced with the area name.
  79.                     %I will be replaced with the area information.
  80.                     %C will be replaced with the area file count.
  81.                     %B will be replaced with the area file size total (bytes).
  82.                     %F will be replaced with the overall file count.
  83.                     %S will be replaced with the overall file size total.
  84.                     %D will be replaced with the report date.
  85.                     %T will be replaced with the report time.
  86.                     %A will be replaced with the age of the files
  87.                        included (or marked) in the report.  Do not use
  88.                        this except with the /D or /M command line
  89.                        parameters!
  90.  
  91.                     Any of these may be followed by an L, R, or C
  92.                     immediately followed by a number.  These will left,
  93.                     right, or center justify the value in a field of the
  94.                     specified width.
  95.  
  96.                     You can also follow any of the above with an NF or
  97.                     with an Fx.  NF stands for "no fill" and has no
  98.                     effect (see examples).  Fx stands for "fill" and
  99.                     will cause the entire field to be replaced by an
  100.                     equivalent number of the character 'x'.  This is
  101.                     useful when drawing boxes.
  102.  
  103.     /Icode      International country code.  This allows you to override
  104.                 the system's country code and pick another format.  Give
  105.                 the DOS country code for the country you want to use.
  106.  
  107.     /Kkeys      Keys to use for access to locked areas.  Keys are
  108.                 represented by 1-8 and A-X.  An asterisk (*) turns on
  109.                 all of the keys.  Multiple keys can be specified in one
  110.                 /K argument (such as /K12B).
  111.  
  112.     /Mdays      Mark new files.  Marks all files less than or equal to
  113.                 this many days old.  You cannot use both this and the /D
  114.                 switch at the same time.
  115.  
  116.     /N          No-wrap.  Leave long description lines intact.  The
  117.                 default is to wrap them.
  118.  
  119.     /O          Include offline files.  By default files that are listed
  120.                 but not present are not included in the list.
  121.  
  122.     /Ppriv      Privilege to use for access to areas.  Only the first
  123.                 letter of the level name is required.  Legal values are:
  124.                     Twit
  125.                     Disgrace
  126.                     Limited
  127.                     Normal
  128.                     Worthy
  129.                     Privil
  130.                     Favored
  131.                     Extra
  132.                     Clerk
  133.                     AsstSysop
  134.                     Sysop
  135.                     Hidden
  136.                 Defaults to Normal.
  137.  
  138.     /T          Truncate long description lines.  The default is to wrap
  139.                 them.
  140.  
  141.     /Vcount     Volume.  'count' is the number of files each dot stands
  142.                 for in the progress indicator.  Zero will turn off all
  143.                 progress displays.
  144.  
  145.     /Wcolumn    Wrap column.  Sets line wrapping to the specified column
  146.                 relative to the left margin.
  147.  
  148. Let me show you an example of how to use the %N and %I parameters in an
  149. area header file (defined with the /HA switch).  The purpose of those
  150. parameters is to let you build boxes that will conform to the size of
  151. the text produced by %N and %I.  Here is an example of a simple header
  152. box using these parameters:
  153.  
  154. ┌──%NF───┬──%IF───┐
  155. │  %NNF  │  %INF  │
  156. └──%NF───┴──%IF───┘
  157.  
  158. Note that the characters following the %NF and %IF look like a part of
  159. the regular text, but are actually the characters that will be used to
  160. fill out the parameters to the desired length.
  161.  
  162. This will expand to something that looks like this:
  163.  
  164. ┌───────┬───────────────────────────────────────────┐
  165. │  MAX  │  Maximus BBS files and related utilities  │
  166. └───────┴───────────────────────────────────────────┘
  167.  
  168. Now you can see why the apparently useless NF modifier can be useful. It
  169. pads out the shorter embedded codes so that they visually match those in
  170. the surrounding lines.  The following would produce exactly the same
  171. result as the previous example, but it is a lot harder to figure out how
  172. everything will match up:
  173.  
  174. ┌──%NF───┬──%IF───┐
  175. │  %N  │  %I  │
  176. └──%NF───┴──%IF───┘
  177.  
  178. Here is an example using fixed width fields.  This also right justifies
  179. the area name and left justifies the area information:
  180.  
  181. ┌─%NR9F──┬─%IL50F──┐
  182. │ %NR9NF │ %IL50NF │
  183. └─%NR9F──┴─%IL50F──┘
  184.  
  185. Which will expand to something that looks like this:
  186.  
  187. ┌───────────┬────────────────────────────────────────────────────┐
  188. │       MAX │ Maximus BBS files and related utilities            │
  189. └───────────┴────────────────────────────────────────────────────┘
  190.  
  191.  
  192. FLIST returns the following ERRORLEVELS:
  193.     0 = success
  194.     1 = bad command line parameter
  195.     2 = unable to open AREA.DAT
  196.     3 = unable to open header file
  197.     4 = unable to open output file
  198.     5 = not enough memory to run
  199.     6 = string overflow processing header
  200.  
  201. NOTICE:  You may use, copy, and distribute this program freely as long
  202. as you insure that both the executable and the documentation (.DOC)
  203. files are included in the distribution package.  The source code does
  204. not need to be included.  You may modify this program and document, so
  205. long as reasonable credit is given to the original author if a
  206. substantial portion of the original remains intact.  The author is not
  207. responsible for any losses which may occur either directly or indirectly
  208. as a result of using this program.
  209.  
  210. This program uses the Maximus structures written by Scott J. Dudley.
  211.  
  212. HISTORY:
  213. Version 2.6   (3/05/93) -- Added support for international date formats.
  214.                            FLIST now reads the country code and uses the
  215.                            appropriate formats automatically.  The /I
  216.                            options can be used to override the system's
  217.                            country code.
  218. Version 2.5   (1/18/93) -- Added the /M option to mark new files.  Fixed
  219.                            counting of files not present in the list.
  220. Version 2.4   (1/10/93) -- Added the /HS option to allow customized area
  221.                            summary headers in the report.  Added new
  222.                            embedded variables for total and area file
  223.                            counts and file sizes.  Fixed a bug that
  224.                            occurred when inappropriate replacement codes
  225.                            were used in a header.
  226. Version 2.3   (1/10/93) -- Added /W parameter to allow line-wrapping to
  227.                            different lengths.  List "offline" as the
  228.                            size for offline file entries.
  229. Version 2.2  (11/04/92) -- Fixed minor date offsets caused by default
  230.                            timezone and daylight savings adjustments.
  231.                            Added the /V switch to limit screen output.
  232.                            /V0 replaces the /Q switch.
  233. Version 2.1   (8/26/92) -- Added the /Q switch to eliminate the progress
  234.                            display.  Now returns different errorlevels
  235.                            for each possible error.  Fixed problem with
  236.                            headers before comments.
  237. Version 2.0   (8/23/92) -- Added more error checking.
  238. Version 1.9   (8/22/92) -- Added a progress display.  Fixed a memory
  239.                            corruption bug.
  240. Version 1.8   (8/20/92) -- Added fixed width fields with left, right,
  241.                            and centered justification for embedded
  242.                            variables.  Changed the previous codes for
  243.                            embedded variables!  Removed built-in help to
  244.                            reduce memory requirements.
  245. Version 1.7   (8/10/92) -- Added embedded variables to the begin and end
  246.                            headers.  Note: This eliminated the automatic
  247.                            file age comment that used to be included for
  248.                            newfile lists.
  249. Version 1.6   (8/10/92) -- Added the /HA option to allow customized area
  250.                            headers in the report.  This is an expansion
  251.                            of an idea and code by David Powers.
  252. Version 1.5   (8/09/92) -- Added the /HB and /HE options to allow
  253.                            customized beginning and end text in the
  254.                            report.  Added /? help option to print the
  255.                            parameter list.  Added a clearer explanation
  256.                            of /C's effect on area headers.
  257. Version 1.4   (8/07/92) -- Added the /C option to include file list
  258.                            comments.  Added code to recognize free
  259.                            switches so they do not show up in the
  260.                            descriptions.  Fixed error if first entry in
  261.                            AREA.DAT did not include a file area.
  262. Version 1.3   (8/06/92) -- Read the file list filename from AREA.DAT
  263.                            instead of assuming FILES.BBS.
  264. Version 1.2   (8/02/92) -- Added days header for new files list.
  265. Version 1.1   (7/30/92) -- Added file age cutoff.
  266. Version 1.0   (6/30/92) -- Original release.  Written in Borland C.
  267.  
  268.